---
title: GitHub
sidebarTitle: GitHub
---

import Overview from "/snippets/overview.mdx"
import PreBuiltTooling from "/snippets/generated/github/PreBuiltTooling.mdx"
import PreBuiltUseCases from "/snippets/generated/github/PreBuiltUseCases.mdx"

import { StatusWidget } from "/snippets/api-down-watch/status-widget.jsx"

<StatusWidget service="github" />

<Overview />
<PreBuiltTooling />
<PreBuiltUseCases />

## Access requirements
| Pre-Requisites | Status | Comment|
| - | - | - |
| Paid dev account | ✅ Not required | Free GitHub account is sufficient for development. |
| Paid test account | ✅ Not required | Free GitHub account is sufficient for testing. |
| Partnership | ✅ Not required | |
| App review | ✅ Not required | No review process for OAuth Apps. |
| Security audit | ✅ Not required | |


## Setup guide

GitHub offers two types of integrations: OAuth Apps and GitHub Apps. This guide covers setting up an OAuth App, which is simpler for basic API access. For more advanced use cases with fine-grained permissions, consider using a GitHub App instead.

<Steps>
  <Step title="Create a GitHub account">
    1. If you don't already have a GitHub account, go to [GitHub's signup page](https://github.com/signup) and create one.
    2. Sign in to your GitHub account.
  </Step>

  <Step title="Register a new OAuth application">
    1. Navigate to your GitHub account settings by clicking on your profile photo in the top-right corner and selecting **Settings**.
    2. In the left sidebar, click on **Developer settings**.
    3. Select **OAuth Apps** in the left sidebar.
    4. Click the **New OAuth App** button.

    Note: If this is your first time creating an OAuth app, you'll see a **Register a new application** button instead.
  </Step>

  <Step title="Configure your OAuth application">
    Fill in the required fields:

    1. **Application name**: Enter a name for your application. This will be shown to users during the authorization process.
    2. **Homepage URL**: Enter the full URL to your application's homepage.
    3. **Application description** (optional): Provide a description of your application to help users understand what it does.
    4. **Authorization callback URL**: Enter `https://api.nango.dev/oauth/callback`

    This is the URL where GitHub will redirect users after they authorize your application.
  </Step>

  <Step title="Register the application">
    1. Click the **Register application** button.
    2. Your OAuth application is now registered, and you'll be taken to its settings page.
  </Step>

  <Step title="Generate a client secret">
    1. On your OAuth App's settings page, you'll see your **Client ID** displayed at the top.
    2. Click the **Generate a new client secret** button.
    3. GitHub will generate a client secret for your application. Make sure to copy and store this securely, as you won't be able to see it again.

    Note: Treat your client secret like a password. Never share it publicly or include it in client-side code.
  </Step>

  <Step title="Configure your integration in Nango">
    When setting up your GitHub integration in Nango:

    - Use your **Client ID** and **Client Secret** from the previous steps
    - For the authorization URL, use: `https://github.com/login/oauth/authorize`
    - For the token URL, use: `https://github.com/login/oauth/access_token`
    - For the scope, select the appropriate permissions your application needs
  </Step>

  <Step title="Test the OAuth flow">
    1. After configuring your integration in Nango, test the OAuth flow to ensure it works correctly.
    2. The authorization flow will redirect users to GitHub where they can approve access to their account.
    3. After approval, users will be redirected back to your application with an authorization code.
    4. This code will be exchanged for an access token that can be used to make API requests.
  </Step>

  <Step title="Next">
    Follow the [_Quickstart_](/getting-started/quickstart).
  </Step>
</Steps>

<Tip>Need help getting started? Get help in the [community](https://nango.dev/slack).</Tip>


## Useful links

-   [GitHub Developer Documentation](https://docs.github.com/en/developers)
-   [GitHub REST API Documentation](https://docs.github.com/en/rest)
-   [Creating an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app)
-   [Authorizing OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps)
-   [OAuth Scopes for GitHub](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)
-   [Differences between GitHub Apps and OAuth Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps)
-   [Registering a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)
-   [GitHub App Permissions](https://docs.github.com/en/rest/overview/permissions-required-for-github-apps)

## Common Scopes

For a complete list of available OAuth scopes, see the [GitHub documentation on OAuth scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps#available-scopes).

## API gotchas

-   When setting up a GitHub App:
    - The App ID is made of numbers (e.g. 401953)
    - The App Public Link is the URL to your Github App public page (e.g. https://github.com/apps/nango-github-app)
    - The App Private Key needs to be generated in your GitHub App settings and starts with `-----BEGIN RSA PRIVATE KEY-----` (not to be confused with the Client Secrets)
    - The Setup URL (displayed on your Nango integration page) needs to be added to your GitHub App configuration (not to be confused with the Callback URL that can stay empty)
-   When setting up a GitHub App OAuth:
    - The App ID is made of numbers (e.g. 401953)
    - The App Public Link is the URL to your Github App public page (e.g. https://github.com/apps/nango-github-app)
    - The App Private Key needs to be generated in your GitHub App settings and starts with `-----BEGIN RSA PRIVATE KEY-----` (not to be confused with the Client Secrets)
    - The "Callback URL" needs to be filled in with the callback URL which unless customized will be https://api.nango.dev/oauth/callback and the checkbox "Request user authorization (OAuth) during installation" should be checked
    - The checkbox "Redirect on update" under "Post installation" should NOT be checked and the "Setup URL (optional)" should not be accessible
-   There are certain API methods that only work with an OAuth App that will not work with an App. Please check the Github documentation and look for a "Works with Github Apps" header under the endpoint.
-   The `github-app-oauth` is a combination of a Github App and OAuth and should be used when a Github App would need approval to be installed into an organization.
-   Nango supports initiating a connection with a GitHub App using the frontend SDK, but not directly from the [GitHub Marketplace](https://github.com/marketplace). Therefore, you should encourage users to install your GitHub App from your product, rather than from the GitHub Marketplace directly. This is a limitation we plan to fix in the future.


<Note>Contribute API gotchas by [editing this page](https://github.com/nangohq/nango/tree/master/docs/integrations/all/github.mdx)</Note>
